
<p>
<h2>Documentation by Example</h2>

<p>
Import the library and open a database. (Only syncronous database
access is implemented at this time.)
<p>
<pre>var sqlite = require("../sqlite");
var db = sqlite.openDatabaseSync("example.db");
</pre>
<p>
Perform an SQL query on the database:
<p>
<pre>db.query("CREATE TABLE foo (a,b,c)");
</pre>
<p>
This is a more convenient form than the HTML5 syntax for the same
thing, but which is also supported:
<p>
<pre>db.transaction(function(tx) {
  tx.executeSql("CREATE TABLE bar (x,y,z)");
});
</pre>
<p>
This allows the same or similar code to work on the client and
server end (modulo browser support of HTML5 Web SQL).
<p>
Transactions generate either a "commit" or "rollback" event.
<p>
<pre>var rollbacks = 0;
db.addListener("rollback", function () {
  ++rollbacks;
});
</pre>
<p>
Both forms take an optional second parameter which is values to
bind to fields in the query, as an array:
<p>
<pre>db.query("INSERT INTO foo (a,b,c) VALUES (?,?,?)", ['apple','banana',22]);
</pre>
<p>
or as a map:
<p>
<pre>db.query("INSERT INTO bar (x,y,z) VALUES ($x,$y,$zebra)", 
         {$x: 10, $y:20, $zebra:"stripes"});
</pre>
<p>
Also optional is a callback function which is called with an object
representing the results of the query:
<p>
<pre>db.query("SELECT x FROM bar", function (records) {
  process.assert(records.length == 1);
  process.assert(records[0].x == 10);
</pre>
<p>
The HTML5 semantics for the record set also work:
<p>
<pre>  process.assert(records.rows.length == 1);
  process.assert(records.rows.item(0).x == 10);
});
</pre>
<p>
INSERT, UPDATE & DELETE queries set <code>rowsAffected</code> on their result
set object:
<p>
<pre>db.query("UPDATE foo SET a = ? WHERE a = ?", ['orange', 'apple'], function(r) {
  process.assert(r.rowsAffected == 1);
});
</pre>
<p>
They also emit an <code>"update"</code> event.
<p>
INSERT queries set <code>insertId</code>:
<p>
<pre>var insert = db.query("INSERT INTO foo VALUES (1,2,3)");
process.assert(insert.insertId == 2);
</pre>
<p>
Note here that the result set passed to the callback is also
returned by <code>query</code>.
<p>
Multiple-statement queries are supported; each statement's result set is retuned to the callback as a separate parameter:
<p>
<pre>var q = db.query("UPDATE bar SET z=20; SELECT SUM(z) FROM bar;",
                 function (update, select) {
                   process.assert(update.rowsAffected == 1);
                   process.assert(select[0]['SUM(z)'] == 20);
                 });
</pre>
<p>
An array of all result sets is available as the <code>.all</code> property on
each result set:
<p>
<pre>process.assert(q.all[1].length == 1);
</pre>
<p>
HTML5 semantics are supported.
<p>
<pre>db.transaction(function(tx) {
  tx.executeSql("SELECT * FROM foo WHERE c = ?", [3], function(tx,res) {
    process.assert(res.rows.item(0).c == 3);
  });
});
</pre>
<p>
The <code>query</code> and <code>transaction</code> APIs wrap lower level APIs that more
thinly wrap the underlying C api:
<p>
<pre>var stmt = db.prepare("INSERT INTO foo VALUES (?,?,?)");
stmt.bind(1, "curly");
stmt.bind(2, "moe");
stmt.bind(3, "larry");
stmt.step();  // Insert Curly, Moe & Larry
stmt.reset();
stmt.step();  // Insert another row with same stooges
stmt.reset();
stmt.clearBindings();
stmt.bind(2, "lonely");
stmt.step();  // Insert (null, "lonely", null)
stmt.finalize();
</pre>
<p>
Close it:
<p>
<pre>db.close();
</pre>
<p>
<p>
</pre>
<p>
</pre>
<p>
